<html>
<head>
<title>The Twisted Split FAQ</title>
</head>

<body>

<h1>The Twisted Split FAQ</h1>

<h2>What is the Twisted Split?</h2>

<p>
<a href="http://twistedmatrix.com/">Twisted</a> is very large. At last
count, it has around 80 thousand lines of code (yes, that <em>is</em> very
large for a Python project, maybe not so for a C++ project. ;). We are
breaking it into several smaller packages before the 2.0 release.
</p>

<h2>Why is Twisted being split?</h2>

<p>
The biggest reason is to make our release process more
agile. Currently it is very slow. A regression in twisted.names, for
example, could hold up the release of the entire thing, when really it
should only be holding up the release of twisted.names.
</p>

<p>
The other big reason is visibility. Twisted has a ton of
functionality, but many people miss out on it because they don't know
where it is hidden inside Twisted. The Twisted split will give every
sub-project its own web site and thus more visibility.
</p>

<h2>But I liked the monolithic packages. Can I still get them?</h2>

<p>
Yes. Tarball and Windows releases for Twisted and all of its
sub-projects will still be maintained. We encourage maintainers of
packages for OSes with automatic packaging systems to break up the
packages as well, so, for example, Debian will have
python2.3-twisted-core, python2.3-twisted-conch,
python2.3-twisted-names, and so on.
</p>

<h2>Where can I find information about the individual projects?</h2>

<p>
A list of <a
href="http://twistedmatrix.com/trac/wiki/TwistedProjects">Twisted
projects</a> is available on the website.  The list includes maintainer
information and links to project-specific pages with more detailed
information.
</p>

<h2>What are the new packages?</h2>

<p>
    <ul>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedCore">Twisted
      Core</a> - This contains twisted.application, twisted.cred,
      twisted.enterprise, twisted.internet, twisted.manhole,
      twisted.persisted, twisted.protocols<sup><a
      href="#protocols">[1]</a></sup>, twisted.python, twisted.spread,
      twisted.trial</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedConch">Twisted
      Conch</a> - This contains twisted.conch.</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedFlow">Twisted
      Flow</a> - This contains twisted.flow (deprecated).</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedLore">Twisted
      Lore</a> - This contains twisted.lore</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedMail">Twisted
      Mail</a> - This contains twisted.mail; NOTE the mail protocols
      that were in twisted.protocols.(imap4,pop3,smtp) were moved to
      twisted.mail.</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedNames">Twisted
      Names</a> - This contains twisted.names; NOTE
      twisted.protocols.dns was moved to twisted.names.dns.</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedNews">Twisted
      News</a> - This contains twisted.news; NOTE
      twisted.protocols.nntp was moved to twisted.news.nntp</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedPair">Twisted
      Pair</a> - This contains twisted.pair; NOTE ethernet, ip, raw,
      and rawudp protocol support was moved from twisted.protocols to
      twisted.pair. (deprecated)</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedRunner">Twisted
      Runner</a> - This contains twisted.runner.</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedWeb">Twisted
      Web</a> - This contains twisted.web; NOTE that
      twisted.protocols.http was moved to twisted.web.http.</li>

      <li><a href="http://twistedmatrix.com/trac/wiki/TwistedWords">Twisted
      Words</a> - This contains twisted.words; NOTE that twisted.im was
      moved to twisted.words.im, twisted.xish was moved to
      twisted.words.xish, AND the chat protocols (irc, msn, jabber, toc,
      oscar) were moved to twisted.words.protocols.</li>
    </ul>
</p>

<p><a name="protocols">[1]</a>: twisted.protocols is very stripped
down now; it only includes the protocols that didn't belong anywhere
else. It still contains the simple protocols, the helper utilities,
and, ahem, FTP.</p>


<h2>Will I have to rewrite my code? What API changes are there?</h2>

<p>
No existing code should <em>break</em>, however, many modules were
moved. Backwards compatibility support <em>does exist</em>; you will
get a DeprecationWarning if you try to import, e.g.,
twisted.protocols.http notifying you that it has been moved to
twisted.web.http.
</p>

<h2>What about my deployments? What will I have to do to have the new packages?</h2>

<p>
It depends on your OS and how you installed Twisted originally. If
you're using Debian, we are planning on breaking up the Debian
packages to e.g. python2.3-twisted-core, python2.3-twisted-web, and so
on. If you're using Windows, or generally install Twisted from the
tarball or from an SVN checkout, monolithic options will still be
available.
</p>

<p>
If you try to run code that imports a sub-package when that
sub-package is not available on the system, an ImportError will be
raised directing the user to the web site for that particular
sub-project.
</p>

<h2>Why are all the packages still named twisted.<em>subproject</em>?</h2>

<p>
This is controversial. While this does mean that there is a
mashed-together namespace under <code>twisted.</code>, it's also the
simplest thing to do, and means less breakage for user-code, so we're
doing that.
</p>


<h2>When will 2.0 be released?</h2>

<p>
That's hard to tell. I (Christopher Armstrong) am doing most of the
work of the split, but I'm in the middle of a move to Australia and a
new full-time job. Unfortunately doing this split requires a lot of
specific knowledge of how things work, but if you are willing to help,
please see the next question.
</p>

<h2>Where can I see a progress report?</h2>

<p>
<a href="http://twistedmatrix.com/bugs/issue567">http://twistedmatrix.com/bugs/issue567</a>.
</p>


<h2>Can I help?</h2>

<p>
Really, there's not a whole lot to be delegated, unless your name is
Fred Drake. However, talk to <a
href="http://radix.twistedmatrix.com/">Christopher Armstrong</a> via
<a href="mailto:radix@twistedmatrix.com">email</a> or IRC ('radix' on
irc.freenode.net) if you're interested.  </p>

<h2>What does this mean for existing Twisted developers?</h2>

<p>
Not much. The repository is rearranged a bit; protocols have been
moved to their relevant packages and documentation is now stored in
doc/<em>subproject</em>/ instead of everything at the top-level of
doc/. Everything is still in the same repository and everyone still
has the same access levels they used to.
</p>

</body>
</html>
